libURLSetStatusCallback

Type

command

Summary

Sets up a callback message to be sent periodically during uploads and downloads.

Syntax

libURLSetStatusCallback [<messageName>[, <objectLongID>]]

Description

Use the libURLSetStatusCallback command if you want to do periodic tasks (such as updating a progress bar) during a data transfer.

The Internet library periodically updates the URLStatus function during uploads and downloads made with the libURLDownloadToFile, libURLftpUpload, libURLftpUploadFile, put, and load commands, as well as downloads triggered by evaluating an ftp or http URL. Whenever the Internet library updates the URLStatus function, it also sends any callback message you've set up with the libURLSetStatusCallback command.

Callback messages are sent even during blocking uploads and downloads (such as a download started with the put command), so you can use this method to monitor progress for all file transfers.

The callback message is sent with two parameters: the URL and the URL's current status. For example, suppose you execute the following statement to set up a callback message:

    libURLSetStatusCallback \"myProgress\",the long ID of button \"Monitor\"

Then suppose you begin an upload with the following command:

    put field \"Data\" into URL \"ftp://me:mypass@ftp.example.org/myfile\"

Periodically while the text of the field is being uploaded to the file, a "myProgress" message is sent to button "Monitor". The first parameter sent with "myProgress" is the URL (in this case, the URL is "ftp://me:mypass@ftp.example.org/myfile"), and the second parameter is the current status of that URL. The "myProgress" handler might look like this:

    on myProgress pURL, pStatus
        put pStatus into field pURL of stack \"Status Monitor\"
    end myProgress

The URL status parameter is similar to the status returned by the URLStatus function, and is one of the following:

• "queued": on hold until a previous request to the same site is completed
• "contacted": the site has been contacted but no data has been sent or received yet
• "requested": the URL has been requested
• "loading,bytesReceived,bytesTotal": the URL data is being received
• "uploading,bytesReceived,bytesTotal": the file is being uploaded to the URL
• "downloaded": the application has finished downloading the URL
• "uploaded": the application has finished uploading the file to the URL
• "error": an error occurred and the URL was not transferred
• "timeout": the application timed out when attempting to transfer the URL
• empty: the URL was not loaded, or has been unloaded

note

The third item (bytesTotal) in the "loading" or "uploading" status report is empty if it is not possible to determine the total file size. (For example, if an ftp server does not support the SIZE command, it's not possible to determine the file size when downloading a file from that server.)

If multiple file transfers are occurring at the same time, a separate callback message is sent for each URL. If you want your callback handler to treat URLs differently (for example, if you want to display separate progress bars for different URLs, or do one thing with http URLs and something else with ftp URLs), use a switch control structure in the handler.

You cannot have two callback messages set up at the same time for uploads and downloads. If you use the libURLSetStatusCallback command to set up a callback message, the Internet library forgets any callback message you previously set up with the command.

To turn off the callback message, use the following statement:

    libURLSetStatusCallback -- no parameters: turns off the message

If you don't include the messageName and objectLongID parameters, the libURLSetStatusCallback command turns off the callback|callback messages so that updating the URLStatus function does not send any messages.

Important

The libURLSetStatusCallback command is part of the Internet library. To ensure that the command works in a standalone application, you must include this custom library when you create your standalone. In the Inclusions pane of the Standalone Application Settings window, make sure the "Internet" script library is selected.

Parameters

Name	Type	Description
messageName		The name of a message to be sent whenever the URLStatus function is updated.
objectLongID		The long ID of the object to send the message to. If messageName is not empty and objectLongID is not specified then the message will be sent to the revLibURL library stack. The message can be handled in a frontscript, backscript, or library stack.

Examples

libURLSetStatusCallback "putPercentage",the long ID of me

libURLSetStatusCallback myAction,the long ID of button "Upload"

libURLSetStatusCallback "putPercentage" -- sends message to url library. Handle the message in a frontscript, backscript, or stack in use.

libURLSetStatusCallback -- turns off status callback messages

Related

control structure: function, switch

function: URLStatus

glossary: LiveCode custom library, application, standalone application, evaluate, message, URL, callback, command, control structure, main stack, Standalone Application Settings, upload, download, server, HTTP, handler

keyword: URL, ftp, item, http

library: library, Internet library

message: startup, openBackground, preOpenStack, openStack, preOpenCard

command: libURLSetStatusCallback, put, load, group, libURLftpUploadFile, libURLftpUpload, libURLDownloadToFile

Compatibility and Support

Introduced

LiveCode 2.0

OS

mac

windows

linux

web

Platforms

desktop

server